feat(module-state): add configurable pull scheduling with watchdog fallback - #5226

Adds configurable pull scheduling to module-state while keeping push replication live.

Changes:

• Adds interval and visibility-aware pull modes with watchdog recovery.
• Exposes configurable default storage and polling events.
• Updates cookbook preview behavior and tests.

• Files reviewed: 12/12 changed files
• Comments generated: 4
• Review effort level: Balanced

Suppressed comments (2)

packages/modules/state/src/storage/PouchDbSyncStorage.ts:94

• This interval-mode branch does not prevent the existing public sync() method from later starting a bidirectional db.sync(). Calling it creates a continuous pull plus a second live push, bypasses #pullInFlight, and violates the stated single-pull invariant; make sync() honor the configured mode or stop the scheduled pull/live push before switching modes.

    if ((this.#pull.mode ?? PullMode.Live) === PullMode.Live) {
      this.sync();
    } else {
      this._startLivePush();
      this._schedulePulling();

packages/modules/state/src/storage/PouchDbSyncStorage.ts:323

• This is a total-duration deadline rather than a hung-replication watchdog. A healthy pull with multiple requests or batches can run longer than timeout + 5s—the preceding comment notes that timeout only bounds each underlying request—so it will be canceled mid-progress every cycle; use an inactivity watchdog that is refreshed by replication progress, or a separately configurable total deadline.

      const watchdogMs =
        (typeof this.#syncOptions.timeout === 'number' ? this.#syncOptions.timeout : 30000) + 5000;
      const watchdog = setTimeout(() => {
        pull.cancel();
        finish();

• Files reviewed: 12/12 changed files
• Comments generated: 0 new
• Review effort level: Balanced

Suppressed comments (3)

packages/modules/state/src/storage/PouchDbSyncStorage.ts:102

• This stopper cancels the live push and future triggers, but it does not cancel a one-shot pull already running. Calling public sync() during the initial/timer pull therefore starts bidirectional sync alongside that pull until it completes or reaches the watchdog, contradicting the replacement invariant; track the active pull cleanup and invoke it here as well.

      this.#stopNonLivePull = () => {
        push.cancel();
        stopScheduledPulling();
      };

packages/modules/state/src/storage/PouchDbSyncStorage.ts:292

• These teardown registrations do not actually clear the watchdog or remove the direct complete/error/change listeners added below. If disposal cancels a hung replication that emits no terminal event—the failure mode the watchdog handles—the timer and listeners remain alive until the watchdog fires after disposal; register a teardown that calls the shared finish()/cleanup path directly.

    const removePullTeardown = this._addTeardown(() => pull.cancel());
    const removeSubscriptionTeardown = this._addTeardown(subscription);

packages/modules/state/package.json:24

• This new consumer entry point and its pull-scheduling API are absent from packages/modules/state/README.md (the README contains no PouchDbSyncStorage, createDefaultStorage, or pull-mode documentation), despite the PR checklist marking user-facing docs updated. Add persistent usage/default documentation there; a changeset alone will not remain in the package API guide.

    "./default-storage": {
      "import": "./dist/esm/create-default-storage.js",
      "types": "./dist/types/create-default-storage.d.ts"
    },

• Files reviewed: 12/12 changed files
• Comments generated: 1
• Review effort level: Balanced

Suppressed comments (5)

packages/modules/state/src/storage/PouchDbSyncStorage.ts:301

• finish() removes both callbacks from the same teardown array that PouchDbStorage[Symbol.dispose]() is iterating. When disposal invokes the active-pull teardown, these splices remove the current and next entries, so the iterator skips the following timer teardown registered by _schedulePulling() and interval polling continues after disposal. Make disposal iterate a snapshot/clear the array, or avoid mutating the teardown collection from inside a teardown callback.

        removePullTeardown();
        removeSubscriptionTeardown();

packages/modules/state/src/storage/PouchDbSyncStorage.ts:359

• After finish() sets settled and clears the watchdog, a late or currently-dispatching change event can still invoke this direct listener and schedule a new timeout. This is reachable when a change subscriber disposes the storage synchronously because the emitter continues its current listener snapshot; guard armWatchdog so cleanup cannot be undone.

      const armWatchdog = () => {
        clearTimeout(watchdog);
        watchdog = setTimeout(() => {
          pull.cancel();
          finish();
        }, watchdogMs);
      };

packages/modules/state/src/storage/PouchDbSyncStorage.ts:271

• The split pull path likewise never merges syncOptions.pull, so valid pull-only filters, query parameters, and timeouts that worked with db.sync() are ignored as soon as scheduled mode is selected. Build effective pull options from the top-level and nested pull settings, and use the same effective timeout for the watchdog below.

        {
          ...this.#syncOptions,
          live: false,
          retry: false,
          // Guarantees 'complete'/'error' fires even against a backend that never answers a
          // one-shot request - otherwise a single hung poll would wedge #pullInFlight forever,
          // silently turning every later timer/focus trigger into a no-op skip.
          timeout: this.#syncOptions.timeout ?? 30000,
        },

packages/modules/state/src/events/index.ts:55

• The published sync-event catalog in packages/modules/state/docs/events.md:69-87 still lists only four event kinds and says StateSyncEvent.is matches four events. Adding Poll here makes that consumer-facing reference incorrect; add onStateSync.poll and its payload to the table and update the count.

  Poll: StateSyncPollEvent,

packages/modules/state/src/storage/PouchDbSyncStorage.ts:219

• SyncOptions supports per-direction push overrides, but passing the whole object to replicate.to() does not merge syncOptions.push as db.sync() does. In scheduled mode, valid push-only filters, query parameters, and retry settings are therefore silently ignored; merge the nested push options before forcing the live invariant.

This issue also appears in the following locations of the same file:

• line 263
• line 300
• line 353

      {
        ...this.#syncOptions,
        live: true,
        retry: this.#syncOptions.retry ?? true,
      },

• Files reviewed: 13/13 changed files
• Comments generated: 0 new
• Review effort level: Balanced